/*---------------------------------------------------------------------------*\
  =========                 |
  \\      /  F ield         | foam-extend: Open Source CFD
   \\    /   O peration     | Version:     4.1
    \\  /    A nd           | Web:         http://www.foam-extend.org
     \\/     M anipulation  | For copyright notice see file Copyright
-------------------------------------------------------------------------------
License
	This file is part of foam-extend.

	foam-extend is free software: you can redistribute it and/or modify it
	under the terms of the GNU General Public License as published by the
	Free Software Foundation, either version 3 of the License, or (at your
	option) any later version.

	foam-extend is distributed in the hope that it will be useful, but
	WITHOUT ANY WARRANTY; without even the implied warranty of
	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
	General Public License for more details.

	You should have received a copy of the GNU General Public License
	along with foam-extend.  If not, see <http://www.gnu.org/licenses/>.

Class
	Foam::Xfer

Description
	A simple container for copying or transferring objects of type \<T\>.

	The wrapped object of type \<T\> must implement a transfer() method and
	an operator=() copy method.

	Since it is decided upon construction of the Xfer object whether the
	parameter is to be copied or transferred, the contents of the resulting
	Xfer object can be transferred unconditionally. This greatly simplifies
	defining constructors or methods in other classes with mixed
	transfer/copy semantics without requiring 2^N different versions.

	When transferring between dissimilar types, the xferCopyTo() and
	xferMoveTo() functions can prove useful. An example is transferring
	from a DynamicList to a List.  Since the
	List\<T\>::transfer(List\<T\>&) method could result in some allocated
	memory becoming inaccessible, the xferMoveTo() function should be used to
	invoke the correct List\<T\>::transfer(DynamicList\<T\>&) method.

	@code
		dynamicLabelList dynLst;
		...
		labelList plainLst( xferMoveTo<labelList>(dynLst) );
	@endcode

	Of course, since this example is a very common operation, the
	DynamicList::xfer() method transfers to a plain List anyhow.
	It would thus be simpler (and clearer) just to use the following code:

	@code
		dynamicLabelList dynLst;
		...
		labelList plainLst(dynLst.xfer());
	@endcode

SeeAlso
	xferCopy, xferCopyTo, xferMove, xferMoveTo, xferTmp

SourceFiles
	XferI.H

\*---------------------------------------------------------------------------*/

#ifndef Xfer_H
#define Xfer_H

// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //

namespace Foam
{

// Forward declaration of classes
template<class T> class tmp;


template<class T>
class Xfer
{
	// Private data

		//- Pointer to underlying datatype
		mutable T* ptr_;

public:

	// Static data members

		//- Empty Xfer
		static const Xfer<T> zero;

		operator const T*() const { return ptr_; }
		 const T* operator&() const { return ptr_; }
	// Constructors

		//- Store object pointer and manage its deletion
		//  Can also be used later to transfer by assignment
		inline explicit Xfer(T* = 0);

		//- Construct by copying or by transferring the parameter contents
		inline explicit Xfer(T&, bool allowTransfer=false);

		//- Construct by copying the parameter contents
		inline explicit Xfer(const T&);

		//- Construct by transferring the contents
		inline Xfer(const Xfer<T>&);

	// Destructor

		inline ~Xfer();

	// Member Functions

		//- Return a null object reference
		inline static const Xfer<T>& null();

	// Member Operators

		//- Transfer the contents into the object
		inline void operator=(T&);

		//- Transfer the contents into the object
		inline void operator=(const Xfer<T>&);

		//- Reference to the underlying datatype
		inline T& operator()() const;

		//- Pointer to the underlying datatype
		inline T* operator->() const;

};


// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //

/**
 * Construct by copying the contents of the @a arg
 *
 * @sa xferCopyTo, xferMove, xferMoveTo, xferTmp and Foam::Xfer
*/
template<class T>
inline Xfer<T> xferCopy(const T&);

/**
 * Construct by transferring the contents of the @a arg
 *
 * @sa xferCopy, xferCopyTo, xferMoveTo, xferTmp and Foam::Xfer
*/
template<class T>
inline Xfer<T> xferMove(T&);


/**
 * Construct by transferring the contents of the @a arg
 *
 * @sa xferCopy, xferCopyTo, xferMove, xferMoveTo and Foam::Xfer
*/
template<class T>
inline Xfer<T> xferTmp(Foam::tmp<T>&);


/**
 * Construct by copying the contents of the @a arg
 * between dissimilar types
 *
 * @sa xferCopy, xferMove, xferMoveTo, xferTmp and Foam::Xfer
*/
template<class To, class From>
inline Xfer<To> xferCopyTo(const From&);


/**
 * Construct by transferring the contents of the @a arg
 * between dissimilar types
 *
 * @par Example Use
 * @code
 *     dynamicLabelList dynLst;
 *     ...
 *     labelList plainLst( xferMoveTo<labelList>(dynLst) );
 * @endcode
 *
 * @sa xferCopy, xferCopyTo, xferMove, xferTmp and Foam::Xfer
*/
template<class To, class From>
inline Xfer<To> xferMoveTo(From&);


} // End namespace Foam


// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //

#include "XferI.H"

// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //

#endif

// ************************************************************************* //
